<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Overview of the Jacobi Theta Functions</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 3.3.0">
<link rel="up" href="../jacobi_theta.html" title="Jacobi Theta Functions">
<link rel="prev" href="../jacobi_theta.html" title="Jacobi Theta Functions">
<link rel="next" href="jacobi_theta1.html" title="Jacobi Theta Function θ1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../jacobi_theta.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jacobi_theta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="jacobi_theta1.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.jacobi_theta.jacobi_theta_overview"></a><a class="link" href="jacobi_theta_overview.html" title="Overview of the Jacobi Theta Functions">Overview
      of the Jacobi Theta Functions</a>
</h3></div></div></div>
<p>
        The Jacobi Theta functions are a set of four inter-related periodic functions
        of <span class="emphasis"><em>x</em></span> which are expressed in terms of a parameter <span class="emphasis"><em>q</em></span>
        (also called the nome), or a closely related value, τ
<a href="#ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f0" class="footnote" name="math_toolkit.jacobi_theta.jacobi_theta_overview.f0"><sup class="footnote">[8]</sup></a> <a href="#ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f1" class="footnote" name="math_toolkit.jacobi_theta.jacobi_theta_overview.f1"><sup class="footnote">[9]</sup></a> <a href="#ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f2" class="footnote" name="math_toolkit.jacobi_theta.jacobi_theta_overview.f2"><sup class="footnote">[10]</sup></a>.
      </p>
<p>
        They are
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_theta1.svg"></span>

        </p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_theta2.svg"></span>

        </p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_theta3.svg"></span>

        </p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_theta4.svg"></span>

        </p></blockquote></div>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../graphs/jacobi_theta.svg" align="middle"></span>

        </p></blockquote></div>
<p>
        Plots of the four theta functions for <span class="emphasis"><em>q</em></span>=0.15.
      </p>
<p>
        Appropriately multiplied and divided, these four theta functions can be used
        to implement the <a class="link" href="../jacobi/jac_over.html" title="Overview of the Jacobi Elliptic Functions">Jacobi elliptic
        functions</a>; but this is not really recommended, as the existing Boost
        implementations are likely faster and more accurate.
      </p>
<p>
        Most applications will want to use the <span class="emphasis"><em>q</em></span> parameterization
        of the functions: <code class="computeroutput"><a class="link" href="jacobi_theta1.html" title="Jacobi Theta Function θ1">jacobi_theta1</a></code>,
        <code class="computeroutput"><a class="link" href="jacobi_theta2.html" title="Jacobi Theta Function θ2">jacobi_theta2</a></code>,
        <code class="computeroutput"><a class="link" href="jacobi_theta3.html" title="Jacobi Theta Function θ3">jacobi_theta3</a></code>,
        and <code class="computeroutput"><a class="link" href="jacobi_theta4.html" title="Jacobi Theta Function θ4">jacobi_theta4</a></code>,
        where <span class="emphasis"><em>q</em></span> is restricted to the domain (0, 1). These four
        functions are equivalent to Mathematica's <a href="https://reference.wolfram.com/language/ref/EllipticTheta.html" target="_top">EllipticTheta</a>
        function (whose first argument is the function number).
      </p>
<p>
        A second τ parameterization is also provided for all four functions, where
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><img src="../../../equations/jacobi_theta_nome.svg"></span>

        </p></blockquote></div>
<p>
        Note that there is a slight difference between τ in the equation above and
        the <code class="computeroutput"><span class="identifier">tau</span></code> in the Boost function
        signatures. The mathematical τ is assumed to be a purely imaginary number,
        but the Boost argument is real-valued. Boost treats its real-valued argument
        as an imaginary number; that is, it implicitly multiplies the argument by
        <span class="emphasis"><em>i</em></span>. This assumption of τ's imaginarity is not required
        by the mathematics, but it does cover the most common application domains.
      </p>
<h5>
<a name="math_toolkit.jacobi_theta.jacobi_theta_overview.h0"></a>
        <span class="phrase"><a name="math_toolkit.jacobi_theta.jacobi_theta_overview.accuracy_considerations"></a></span><a class="link" href="jacobi_theta_overview.html#math_toolkit.jacobi_theta.jacobi_theta_overview.accuracy_considerations">Accuracy
        considerations</a>
      </h5>
<p>
        The purpose of the τ parameterization is to provide increased accuracy either
        when <span class="emphasis"><em>q</em></span> is expressible as an exponential or is very close
        to unity. For example, instead of:
      </p>
<pre class="programlisting"><span class="identifier">jacobi_theta1</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">(-</span><span class="identifier">a</span><span class="special">));</span>
</pre>
<p>
        A more accurate computation will take advantage of τ:
      </p>
<pre class="programlisting"><span class="identifier">jacobi_theta1tau</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">a</span> <span class="special">/</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;());</span>
</pre>
<p>
        Internally, Boost implements the <span class="emphasis"><em>q</em></span> parameterization
        by taking the logarithm of <span class="emphasis"><em>q</em></span> and passing it to the τ parameterization;
        as such, using the τ parameterization directly will generally yield greater
        precision. As another example, if the complement of <span class="emphasis"><em>q</em></span>
        is known with great accuracy, then instead of:
      </p>
<pre class="programlisting"><span class="identifier">jacobi_theta1</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="number">1</span><span class="special">-</span><span class="identifier">q_complement</span><span class="special">);</span>
</pre>
<p>
        It is more accurate to use <code class="computeroutput"><a class="link" href="../powers/log1p.html" title="log1p">log1p</a></code>
        and pass in the result to the τ version:
      </p>
<pre class="programlisting"><span class="identifier">jacobi_theta1tau</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="special">-</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">log1p</span><span class="special">(-</span><span class="identifier">q_complement</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;());</span>
</pre>
<p>
        Additional "minus 1" versions of the third and fourth theta functions
        are provided. Similar in spirit to <code class="computeroutput"><a class="link" href="../powers/expm1.html" title="expm1">expm1</a></code>,
        these functions return one less than the evaluated function, and yield increased
        accuracy when <span class="emphasis"><em>q</em></span> is small.
      </p>
<h5>
<a name="math_toolkit.jacobi_theta.jacobi_theta_overview.h1"></a>
        <span class="phrase"><a name="math_toolkit.jacobi_theta.jacobi_theta_overview.testing"></a></span><a class="link" href="jacobi_theta_overview.html#math_toolkit.jacobi_theta.jacobi_theta_overview.testing">Testing</a>
      </h5>
<p>
        Results of the theta functions are tested against Wolfram Alpha data, as
        well as random values computed at high precision. In addition, the tests
        verify the majority of the identities described in <a href="https://dlmf.nist.gov/20.7" target="_top">DLMF
        Chapter 20.7</a>.
      </p>
<div class="footnotes">
<br><hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f0" class="footnote"><p><a href="#math_toolkit.jacobi_theta.jacobi_theta_overview.f0" class="para"><sup class="para">[8] </sup></a>
          <a href="https://en.wikipedia.org/wiki/Theta_function" target="_top">Wikipedia: Theta
          function</a>
        </p></div>
<div id="ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f1" class="footnote"><p><a href="#math_toolkit.jacobi_theta.jacobi_theta_overview.f1" class="para"><sup class="para">[9] </sup></a>
          <a href="https://mathworld.wolfram.com/JacobiThetaFunctions.html" target="_top">Weisstein,
          Eric W. "Jacobi Theta Functions." From MathWorld - A Wolfram
          Web Resource.</a>
        </p></div>
<div id="ftn.math_toolkit.jacobi_theta.jacobi_theta_overview.f2" class="footnote"><p><a href="#math_toolkit.jacobi_theta.jacobi_theta_overview.f2" class="para"><sup class="para">[10] </sup></a>
          <a href="https://dlmf.nist.gov/20" target="_top">Digital Library of Mathematical Functions:
          Theta Functions, Reinhardt, W. P., Walker, P. L.</a>
        </p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../jacobi_theta.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jacobi_theta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="jacobi_theta1.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
